Perbandingan mendalam setup.py dan pyproject.toml untuk manajemen paket Python, meliputi praktik terbaik, strategi migrasi, dan alat modern.
Struktur Paket Python: Setup.py vs. Pyproject.toml - Panduan Komprehensif
Selama bertahun-tahun, file setup.py adalah landasan manajemen paket Python. Namun, lanskap telah berkembang, dan pyproject.toml telah muncul sebagai alternatif modern. Panduan komprehensif ini mengeksplorasi perbedaan antara kedua pendekatan ini, membantu Anda memahami mana yang tepat untuk proyek Anda dan bagaimana mengelola paket Python Anda secara efektif.
Memahami Dasar-Dasar
Apa itu Paket Python?
Paket Python adalah cara untuk mengatur dan mendistribusikan kode Python Anda. Ini memungkinkan Anda untuk mengelompokkan modul terkait ke dalam hierarki direktori, membuat kode Anda lebih modular, dapat digunakan kembali, dan mudah dipelihara. Paket sangat penting untuk berbagi kode Anda dengan orang lain dan untuk mengelola dependensi dalam proyek Anda.
Peran Metadata Paket
Metadata paket menyediakan informasi penting tentang paket Anda, seperti nama, versi, penulis, dependensi, dan titik masuknya. Metadata ini digunakan oleh pengelola paket seperti pip untuk menginstal, memutakhirkan, dan mengelola paket Anda. Secara historis, setup.py adalah cara utama untuk menentukan metadata ini.
Setup.py: Pendekatan Tradisional
Apa itu Setup.py?
setup.py adalah skrip Python yang menggunakan perpustakaan setuptools untuk menentukan struktur dan metadata paket Anda. Ini adalah file yang dieksekusi secara dinamis, yang berarti menjalankan kode Python untuk mengonfigurasi paket.
Komponen Utama Setup.py
File setup.py yang khas menyertakan komponen-komponen berikut:
- Nama Paket: Nama paket Anda (misalnya,
my_package). - Versi: Nomor versi paket Anda (misalnya,
1.0.0). - Informasi Penulis dan Pemelihara: Rincian tentang penulis dan pemelihara paket.
- Dependensi: Daftar paket lain yang bergantung pada paket Anda (misalnya,
requests >= 2.20.0). - Titik Masuk: Definisi untuk skrip baris perintah atau titik masuk lain ke paket Anda.
- Data Paket: File non-kode (misalnya, file konfigurasi, file data) yang harus disertakan dalam paket.
Contoh Setup.py
```python from setuptools import setup, find_packages setup( name='my_package', version='1.0.0', author='John Doe', author_email='john.doe@example.com', description='A simple Python package', packages=find_packages(), install_requires=[ 'requests >= 2.20.0', ], entry_points={ 'console_scripts': [ 'my_script = my_package.module:main', ], }, classifiers=[ 'Programming Language :: Python :: 3', 'License :: OSI Approved :: MIT License', 'Operating System :: OS Independent', ], ) ```Keuntungan Setup.py
- Keakraban: Ini adalah pendekatan tradisional dan terkenal, jadi banyak pengembang sudah terbiasa dengannya.
- Fleksibilitas: Karena ini adalah skrip Python, ia menawarkan fleksibilitas tingkat tinggi. Anda dapat melakukan logika yang kompleks dan menyesuaikan proses build sesuai kebutuhan.
- Ekstensibilitas: Setuptools menyediakan serangkaian fitur yang kaya dan dapat diperluas dengan perintah dan ekstensi khusus.
Kerugian Setup.py
- Eksekusi Dinamis: Sifat dinamis
setup.pydapat menjadi risiko keamanan, karena menjalankan kode arbitrer selama proses build. - Dependensi Implisit:
setup.pyseringkali bergantung pada dependensi implisit, seperti setuptools itu sendiri, yang dapat menyebabkan inkonsistensi dan kesalahan. - Kompleksitas: Untuk proyek yang kompleks,
setup.pydapat menjadi besar dan sulit untuk dipelihara. - Konfigurasi Deklaratif Terbatas: Sebagian besar metadata paket didefinisikan secara imperatif daripada secara deklaratif, sehingga lebih sulit untuk dipikirkan.
Pyproject.toml: Alternatif Modern
Apa itu Pyproject.toml?
pyproject.toml adalah file konfigurasi yang menggunakan format TOML (Tom's Obvious, Minimal Language) untuk menentukan sistem build dan metadata paket Anda. Ini adalah pendekatan deklaratif, yang berarti Anda menentukan apa yang ingin Anda capai, bukan bagaimana mencapainya.
Bagian Utama Pyproject.toml
Filepyproject.toml yang khas menyertakan bagian-bagian berikut:
[build-system]: Menentukan sistem build yang akan digunakan (misalnya,setuptools,poetry,flit).[project]: Berisi metadata tentang proyek, seperti nama, versi, deskripsi, penulis, dan dependensinya.[tool.poetry]atau[tool.flit]: Bagian untuk konfigurasi khusus alat (misalnya, Puisi, Flit).
Contoh Pyproject.toml (dengan Setuptools)
```toml [build-system] requires = ["setuptools>=61.0"] build-backend = "setuptools.build_meta" [project] name = "my_package" version = "1.0.0" description = "A simple Python package" authors = [ { name = "John Doe", email = "john.doe@example.com" } ] dependencies = [ "requests >= 2.20.0", ] [project.scripts] my_script = "my_package.module:main" [project.optional-dependencies] dev = [ "pytest", "flake8", ] [project.classifiers] classifiers = [ "Programming Language :: Python :: 3", "License :: OSI Approved :: MIT License", "Operating System :: OS Independent", ] [project.urls] homepage = "https://example.com" repository = "https://github.com/example/my_package" ```Contoh Pyproject.toml (dengan Puisi)
```toml [tool.poetry] name = "my_package" version = "1.0.0" description = "A simple Python package" authors = ["John DoeKeuntungan Pyproject.toml
- Konfigurasi Deklaratif:
pyproject.tomlmenyediakan cara deklaratif untuk menentukan metadata paket Anda, sehingga lebih mudah dipahami dan dipelihara. - Sistem Build Standar: Ini menentukan sistem build yang akan digunakan, memastikan build yang konsisten di berbagai lingkungan.
- Peningkatan Manajemen Dependensi: Alat seperti Poetry dan Pipenv berintegrasi secara mulus dengan
pyproject.tomluntuk menyediakan fitur manajemen dependensi yang kuat. - Mengurangi Risiko Keamanan: Karena ini adalah file konfigurasi statis, ini menghilangkan risiko keamanan yang terkait dengan eksekusi kode secara dinamis selama proses build.
- Integrasi dengan Alat Modern:
pyproject.tomladalah standar untuk alat pengemasan Python modern seperti Poetry, Pipenv, dan Flit.
Kerugian Pyproject.toml
- Kurva Pembelajaran: Pengembang mungkin perlu mempelajari sintaks baru (TOML) dan cara baru berpikir tentang manajemen paket.
- Fleksibilitas Terbatas: Mungkin tidak cocok untuk proses build yang sangat disesuaikan yang memerlukan logika kompleks.
- Ketergantungan Alat: Anda harus memilih dan mempelajari cara menggunakan sistem build tertentu (misalnya, Setuptools, Poetry, Flit).
Membandingkan Setup.py dan Pyproject.toml
Berikut adalah tabel yang merangkum perbedaan utama antara setup.py dan pyproject.toml:
| Fitur | Setup.py | Pyproject.toml |
|---|---|---|
| Gaya Konfigurasi | Imperatif (kode Python) | Deklaratif (TOML) |
| Sistem Build | Implisit (Setuptools) | Eksplisit (ditentukan dalam [build-system]) |
| Keamanan | Potensi kurang aman (eksekusi dinamis) | Lebih aman (konfigurasi statis) |
| Manajemen Dependensi | Dasar (install_requires) |
Tingkat Lanjut (integrasi dengan Poetry, Pipenv) |
| Alat | Tradisional (Setuptools) | Modern (Poetry, Pipenv, Flit) |
| Fleksibilitas | Tinggi | Sedang |
| Kompleksitas | Bisa tinggi untuk proyek yang kompleks | Umumnya lebih rendah |
Strategi Migrasi: Dari Setup.py ke Pyproject.toml
Bermigrasi dari setup.py ke pyproject.toml mungkin tampak menakutkan, tetapi ini adalah investasi yang berharga untuk keberlanjutan dan konsistensi jangka panjang. Berikut adalah beberapa strategi yang dapat Anda gunakan:
1. Mulai dengan Pyproject.toml Minimal
Buat file pyproject.toml dasar yang menentukan sistem build dan kemudian secara bertahap memigrasikan metadata dari setup.py ke pyproject.toml.
2. Gunakan Setuptools dengan Pyproject.toml
Terus gunakan Setuptools sebagai sistem build Anda, tetapi tentukan metadata proyek dalam pyproject.toml. Ini memungkinkan Anda untuk memanfaatkan manfaat pyproject.toml sambil tetap menggunakan alat yang sudah dikenal.
3. Migrasi ke Alat Modern seperti Poetry
Pertimbangkan untuk bermigrasi ke alat modern seperti Poetry atau Pipenv. Alat-alat ini menyediakan fitur manajemen dependensi yang komprehensif dan berintegrasi secara mulus dengan pyproject.toml.
Contoh: Bermigrasi ke Puisi
- Instal Puisi:
pip install poetry - Inisialisasi Puisi dalam proyek Anda:
poetry init(Ini akan memandu Anda membuat filepyproject.toml) - Tambahkan dependensi Anda:
poetry add requests(atau dependensi lainnya) - Bangun paket Anda:
poetry build
4. Gunakan Alat untuk Migrasi Otomatis
Beberapa alat dapat membantu mengotomatiskan proses migrasi. Misalnya, Anda dapat menggunakan alat untuk mengonversi file setup.py Anda menjadi file pyproject.toml.
Praktik Terbaik untuk Manajemen Paket Python
1. Gunakan Lingkungan Virtual
Selalu gunakan lingkungan virtual untuk mengisolasi dependensi proyek Anda dari instalasi Python di seluruh sistem. Ini mencegah konflik dan memastikan bahwa proyek Anda memiliki dependensi yang benar.
Contoh menggunakan venv:
Contoh menggunakan conda:
2. Tentukan Dependensi Secara Akurat
Gunakan batasan versi untuk menentukan versi yang kompatibel dari dependensi Anda. Ini mencegah perilaku tak terduga yang disebabkan oleh pembaruan pustaka yang tidak kompatibel. Gunakan alat seperti pip-tools untuk mengelola dependensi Anda.
Contoh spesifikasi dependensi:
``` requests >= 2.20.0, < 3.0.0 ```3. Gunakan Sistem Build yang Konsisten
Pilih sistem build (misalnya, Setuptools, Poetry, Flit) dan patuhi itu. Ini memastikan build yang konsisten di berbagai lingkungan dan menyederhanakan proses pengemasan.
4. Dokumentasikan Paket Anda
Tulis dokumentasi yang jelas dan ringkas untuk paket Anda. Ini membantu pengguna memahami cara menggunakan paket Anda dan memudahkan orang lain untuk berkontribusi pada proyek Anda. Gunakan alat seperti Sphinx untuk menghasilkan dokumentasi dari kode Anda.
5. Gunakan Integrasi Berkelanjutan (CI)
Siapkan sistem CI (misalnya, GitHub Actions, Travis CI, GitLab CI) untuk secara otomatis membangun, menguji, dan menyebarkan paket Anda setiap kali perubahan dilakukan pada kode Anda. Ini membantu memastikan bahwa paket Anda selalu dalam keadaan berfungsi.
Contoh konfigurasi GitHub Actions:
```yaml name: Python Package on: push: branches: [ main ] pull_request: branches: [ main ] jobs: build: runs-on: ubuntu-latest steps: - uses: actions/checkout@v3 - name: Set up Python 3.9 uses: actions/setup-python@v4 with: python-version: 3.9 - name: Install dependencies run: | python -m pip install --upgrade pip pip install poetry poetry install - name: Lint with flake8 run: | poetry run flake8 . - name: Test with pytest run: | poetry run pytest ```6. Publikasikan Paket Anda ke PyPI
Bagikan paket Anda dengan dunia dengan mempublikasikannya ke Python Package Index (PyPI). Ini memudahkan orang lain untuk menginstal dan menggunakan paket Anda.
Langkah-langkah untuk mempublikasikan ke PyPI:
- Daftarkan akun di PyPI dan TestPyPI.
- Instal
twine:pip install twine. - Bangun paket Anda:
poetry buildataupython setup.py sdist bdist_wheel. - Unggah paket Anda ke TestPyPI:
twine upload --repository testpypi dist/*. - Unggah paket Anda ke PyPI:
twine upload dist/*.
Contoh Dunia Nyata
Mari kita lihat bagaimana beberapa proyek Python populer menggunakan pyproject.toml:
- Puisi: Menggunakan
pyproject.tomluntuk manajemen paketnya sendiri. - Black: Pemformat kode tanpa kompromi juga menggunakan
pyproject.toml. - FastAPI: Kerangka kerja web modern, cepat (berkinerja tinggi), untuk membangun API dengan Python juga menggunakannya.
Kesimpulan
pyproject.toml mewakili standar modern untuk manajemen paket Python, menawarkan cara deklaratif dan aman untuk menentukan metadata paket Anda dan mengelola dependensi. Meskipun setup.py telah melayani kita dengan baik, bermigrasi ke pyproject.toml adalah investasi yang berharga untuk keberlanjutan, konsistensi, dan integrasi jangka panjang dengan alat modern. Dengan mengadopsi praktik terbaik dan memanfaatkan alat yang tepat, Anda dapat merampingkan alur kerja pengemasan Python Anda dan membuat paket berkualitas tinggi yang dapat digunakan kembali.